<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.13.1: http://docutils.sourceforge.net/" />
<title>Fast Neurite Tracer</title>
<meta name="author" content="GOU Lingfeng" />
<meta name="date" content="24 Feb 2017" />
<meta name="copyright" content="GFDLv1.2+" />
<link rel="stylesheet" href="style.css" type="text/css" />
<link rel="stylesheet" href="/usr/lib/python2.7/site-packages/docutils/writers/html5_polyglot/math.css" type="text/css" />
</head>
<body>
<div class="document" id="fast-neurite-tracer">
<h1 class="title">Fast Neurite Tracer</h1>
<h2 class="subtitle" id="user-manual">User Manual</h2>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>GOU Lingfeng</td></tr>
<tr><th class="docinfo-name">Contact:</th>
<td><a class="first last reference external" href="mailto:goulf&#64;ion.ac.cn">goulf&#64;ion.ac.cn</a></td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>24 Feb 2017</td></tr>
<tr class="web-site field"><th class="docinfo-name">Web site:</th><td class="field-body"><a class="reference external" href="https://fast-neurite-tracer.sourceforge.io/">https://fast-neurite-tracer.sourceforge.io/</a></td>
</tr>
<tr><th class="docinfo-name">Copyright:</th>
<td><a class="first reference external" href="http://www.gnu.org/licenses/fdl.html">GFDLv1.2+</a></td></tr>
<tr><th class="docinfo-name">Version:</th>
<td>1.0</td></tr>
</tbody>
</table>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#introduction" id="id3">Introduction</a><ul>
<li><a class="reference internal" href="#definition-of-terms" id="id4">Definition of Terms</a></li>
</ul>
</li>
<li><a class="reference internal" href="#preparation" id="id5">Preparation</a><ul>
<li><a class="reference internal" href="#affine-transformation" id="id6">Affine Transformation</a></li>
<li><a class="reference internal" href="#big-data-conversion" id="id7">Big Data Conversion</a></li>
<li><a class="reference internal" href="#catalog-file" id="id8">CATALOG File</a></li>
</ul>
</li>
<li><a class="reference internal" href="#browsing-data" id="id9">Browsing Data</a><ul>
<li><a class="reference internal" href="#zooming" id="id10">Zooming</a></li>
<li><a class="reference internal" href="#rotation" id="id11">Rotation</a></li>
<li><a class="reference internal" href="#visualization" id="id12">Visualization</a></li>
<li><a class="reference internal" href="#change-current-position" id="id13">Change Current Position</a></li>
<li><a class="reference internal" href="#pick-target-position" id="id14">Pick Target Position</a></li>
<li><a class="reference internal" href="#data-loading" id="id15">Data Loading</a></li>
<li><a class="reference internal" href="#annotation" id="id16">Annotation</a></li>
</ul>
</li>
<li><a class="reference internal" href="#tracing" id="id17">Tracing</a><ul>
<li><a class="reference internal" href="#finding" id="id18">Finding</a></li>
<li><a class="reference internal" href="#examining" id="id19">Examining</a></li>
<li><a class="reference internal" href="#accepting" id="id20">Accepting</a></li>
<li><a class="reference internal" href="#traversal" id="id21">Traversal</a></li>
<li><a class="reference internal" href="#deletion" id="id22">Deletion</a></li>
<li><a class="reference internal" href="#modififcation" id="id23">Modififcation</a></li>
<li><a class="reference internal" href="#neurons" id="id24">Neurons</a></li>
<li><a class="reference internal" href="#shortcut-keys" id="id25">Shortcut Keys</a></li>
<li><a class="reference internal" href="#miscellaneous" id="id26">Miscellaneous</a></li>
</ul>
</li>
<li><a class="reference internal" href="#configuration" id="id27">Configuration</a><ul>
<li><a class="reference internal" href="#cache" id="id28">Cache</a></li>
<li><a class="reference internal" href="#loading" id="id29">Loading</a></li>
<li><a class="reference internal" href="#channels" id="id30">Channels</a></li>
<li><a class="reference internal" href="#display" id="id31">Display</a></li>
<li><a class="reference internal" href="#computation" id="id32">Computation</a></li>
</ul>
</li>
<li><a class="reference internal" href="#tools" id="id33">Tools</a></li>
<li><a class="reference internal" href="#id2" id="id34">Miscellaneous</a><ul>
<li><a class="reference internal" href="#files-and-directories" id="id35">Files and Directories</a></li>
<li><a class="reference internal" href="#license" id="id36">License</a></li>
<li><a class="reference internal" href="#author" id="id37">Author</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="introduction">
<h1><a class="toc-backref" href="#table-of-contents">Introduction</a></h1>
<p>Fast Neurite Tracer (FNT) is a tool for semi-automated neurite tracing.
FNT can handle big imaging data such as fMOST data.
It can also process other types of light imaging data in general.
FNT is designed to be</p>
<ul class="simple">
<li>accurate in tracing (each tracing step needs your confirmation),</li>
<li>fast (operations using computer mouse is reduced with automatic searching),</li>
<li>scalable (large volume data of tera-bytes in size are supported).</li>
</ul>
<p>Other features include</p>
<ul class="simple">
<li>the results can be exported to SWC files,</li>
<li>automatic detection of cycles during tracing,</li>
<li>support for data of multiple channels,</li>
<li>support for both 8-bit and 16-bit image data.</li>
</ul>
<div class="section" id="definition-of-terms">
<h2><a class="toc-backref" href="#table-of-contents">Definition of Terms</a></h2>
<p>Some commonly used terms in FNT are defined here:</p>
<dl class="docutils">
<dt>Tracing</dt>
<dd>The reconstruction of neurons, especially neurites including both axons
and dendrites.</dd>
<dt>Node</dt>
<dd>A reconstructed neuron is represented by a collection of connected nodes
in a tree structure.
Nodes are associated with the properties including 3D positions, radii
and types.</dd>
<dt>Edge</dt>
<dd>Nodes connected in a linear structure, flanked by branching nodes or
terminal nodes, are collectively called an edge.
Note that a branching node is associated with multiple edges.</dd>
<dt>Vertex</dt>
<dd>End points of edges, namely branching nodes or terminal nodes.</dd>
<dt>Putative Path</dt>
<dd>Collection of nodes in a linear structure, returned by the execution of
an algorithm, that is used to extend an existing edge or to create
a new edge.
A putative path is not included in the tracing results until being
confirmed by the user.</dd>
<dt>Current Position</dt>
<dd>The 3D location around which visualization and calculations are performed.
It is located at the center of the 3D viewer and represented by a circle.</dd>
<dt>Current Edge</dt>
<dd>If the current position is on an edge, then that edge is the current edge.</dd>
<dt>Target Position</dt>
<dd>The 3D location picked by the user.
It is represented by a cross.</dd>
<dt>Target Edge</dt>
<dd>If the target position is on an edge, then that edge is the target edge.</dd>
</dl>
</div>
</div>
<div class="section" id="preparation">
<h1><a class="toc-backref" href="#table-of-contents">Preparation</a></h1>
<p>To get started, you need to load imaging data for tracing first.
You can either choose and open a previously saved FNT file (<span class="ui">File/Open</span>)
or create a new FNT file (<span class="ui">File/New</span>).
Creating new FNT files requires the location of imaging data and an optional
<a class="reference internal" href="#affine-transformation">affine transformation</a> matrix as input.</p>
<p>For small imaging data in a single file, you can specify the file path,
or URL if it is in a remote computer, and open it directly.
The file format can be either multi-image TIFF file or 3D NRRD file.
Whether a file is small enough to be opened directly depends on the computer
hardware and current computer state like memory usage.
Some basic requirements are</p>
<ul class="simple">
<li>there is enough main memory for uncompressed 3D data,</li>
<li>there is enough GPU memory for uncompressed 3D data,</li>
<li>image size in each direction is not larger than <code class="cl C"><span class="name">GL_MAX_3D_TEXTURE_SIZE</span></code>.</li>
</ul>
<p>Big imaging data in a series of TIFF files need to be
<a class="reference internal" href="#big-data-conversion">converted</a> to small cubes.
The location (path or URL) of the CATALOG file generated during conversion
is used to load the big imaging data.</p>
<p>Multiple image files or CATALOG files can be combined by writing a new
<a class="reference internal" href="#catalog-file">CATALOG file</a>.
FNT supports data of multiple channels in this approach.</p>
<div class="section" id="affine-transformation">
<h2><a class="toc-backref" href="#table-of-contents">Affine Transformation</a></h2>
<div class="figure align-center" style="width: 80%">
<img alt="Affine transformation examples" id="affine-xform" src="affine-xform.png" style="width: 80%;" />
<p class="caption">Affine transformation examples.</p>
<div class="legend">
<span class="fig">A</span> and <span class="fig">B</span> are examples of creating new FNT files.
<span class="fig">C</span> and <span class="fig">D</span> are examples of writing CATALOG files.</div>
</div>
<p>Detailed explanation of affine transformation is available at its
<a class="reference external" href="https://en.wikipedia.org/wiki/Affine_transformation">Wikipedia page</a>.
FNT uses affine transformation to specify image resolution or to align
multiple image volumes.
The followings are some examples of using affine transformation in FNT.</p>
<p>When creating a new FNT file with a CATALOG file as input, the
transformation matrix is typically left unchanged (<span class="fig">A</span>).
Usually, resolution information is specified in CATALOG
file already and there is no need to do further transformation.</p>
<p>With a single image file, the affine transformation is typically used to
specify image resolution.
Many TIFF files provide no resolution information and some provide
wrong resolution information.
There is no standard way for TIFF files to provide Z resolution.
Therefore FNT does not automatically obtain resolution information from file
and affine transformation matrix is used to manually specify image resolution.
Here the file <span class="fn">test.tiff</span> is specified with
X/Y resolution 0.3 µm/pixel and Z resolution 1µm/pixel (<span class="fig">B</span>).</p>
<p>Suppose TIFF file <span class="fn">a.tiff</span> has voxel size of 0.5µm/0.5µm/2µm.
File <span class="fn">b.tiff</span> is the same as <span class="fn">a.tiff</span> except that the first five slices
are missing.
They can be aligned and combined if the correct transformation matrix is given
in the CATALOG file (<span class="fig">C</span>).</p>
<p>In a real example, some neurons are traced on one hemisphere of the
mouse brain, while the injection sites for most of Allen Brain Atlas (ABA)
projection experiments are on the other hemisphere.
To compare the traced results with ABA projection experiments,
we can obtain the mirror image of all reformatted ABA projection density
images by the transformation.
The transformation matrix given here is calculated from a mirror
plane (<span class="fig">D</span>).</p>
<p>Note that, in CATALOG files, the <span class="prop">origin</span> property corresponds to
the column vector on the right side of the dialog box and the
<span class="prop">direction</span> property corresponds to the 3x3 matrix on the left side
in column-major order.</p>
</div>
<div class="section" id="big-data-conversion">
<h2><a class="toc-backref" href="#table-of-contents">Big Data Conversion</a></h2>
<p>Big imaging data that cannot be loaded at a time is split to
small cubes using the <code class="sh bash">fnt-slice2cube</code> command.
Run <code class="sh bash">fnt-slice2cube --help</code> for help on detailed usage.
The following is a simple example.</p>
<p>Suppose we have the following files</p>
<pre class="code bash literal-block">
$ ls *.tif
image1.tif  image2.tif  image3.tif  image4.tif  image6.tif
</pre>
<p>The resolution for each file is 0.3µm/pixel and each slice is 2µm thick.</p>
<p>First create a list of file names</p>
<pre class="code bash literal-block">
$ ls *.tif &gt; list
$ cat list
image1.tif
image2.tif
image3.tif
image4.tif
image6.tif
$ wc list
 <span class="literal number">5</span>  <span class="literal number">5</span> <span class="literal number">55</span> list
</pre>
<p>There are 5 files in the list, but 6 files are expected
(<tt class="docutils literal">image1.tif</tt> to <tt class="docutils literal">image6.tif</tt>).
So use a text editor and add one line to remedy the missing file</p>
<pre class="code bash literal-block">
$ vi list
$ cat list
image1.tif
image2.tif
image3.tif
image4.tif
BLACK
image6.tif
</pre>
<p>Then start the conversion</p>
<pre class="code bash literal-block">
$ fnt-slice2cube -i list -r 0.3:0.3:2 -c 256:256:6 -d 16:16:1 -o cubes
</pre>
<p>It is important to set the right cube sizes and downsample factors.
If the cube sizes are too big, they may fail to be loaded into
the graphics card.
If the cube sizes are too small, too many small files will be generated
and that lowers file system efficiency.
If the downsample factors are too small, the downsampled channel will be
too big to be loaded.
If the downsample factors are too big, the resolution of the downsampled
channel will be too low.
Besides, the cube sizes should better be chosen such that the resulting cubes
have similar physical lengths at X/Y/Z directions.
The downsample factors should better be chosen such that downsampled image
has similar resolutions at X/Y/Z directions.</p>
<p>It is also possible to do simple conversion, without splitting or
downsampling, by specifying <code class="sh bash">-d 1:1:1</code> in the command line arguments.
A series of single-image TIFF files cannot be directly opened by FNT as
a single volume.
In addition, the extra channels in a multi-channel multi-image TIFF file
are ignored by FNT.
In these two cases, simple conversion helps.</p>
</div>
<div class="section" id="catalog-file">
<h2><a class="toc-backref" href="#table-of-contents">CATALOG File</a></h2>
<p>FNT uses a CATALOG file to organize multiple channels in a dataset.
It is an <a class="reference external" href="https://en.wikipedia.org/wiki/INI_file">INI file</a> with
restricted properties.</p>
<div class="figure align-center" style="width: 80%">
<img alt="CATALOG file examples" id="id1" src="catalog-file.png" style="width: 80%;" />
<p class="caption">CATALOG file examples.</p>
<div class="legend">
<span class="fig">A</span> is a CATALOG file containing 4 sections.
<span class="fig">B</span> is the CATALOG file referred to in section 4 (allen-proj)
of <span class="fig">A</span>.
<span class="fig">C</span> is the annotation file refered to in section 3 (annot)
of <span class="fig">A</span>.</div>
</div>
<p>The section for a single image file has the <span class="prop">location</span> property,
which is the path or URL of the image file (section 2 in <span class="fig">A</span>).</p>
<p>The section for converted big imaging data has the <span class="prop">pattern</span>
property (section 1 in <span class="fig">A</span>).
The pattern, when substituted with X/Y/Z coordinates, provides the paths
or URLs of small cubes.
For example, <span class="fn">ch1/z&lt;08Z&gt;/y&lt;08Y&gt;.x&lt;08X&gt;.nrrd</span> denotes the file
<span class="fn">ch1/z00000120/y00004096.x00000256.nrrd</span> when substituted with
X/Y/Z coordinates <span class="formula">(256, 4096, 120)</span>.
The pattern is similar to that used by the C function <code class="cl C"><span class="name">printf</span></code>.
Size information for the whole volume and for each small cube is also required.
The properties <span class="prop">size</span> and <span class="prop">cubesize</span> are for this purpose.</p>
<p>Section containing the link to another CATALOG file require the <span class="prop">link</span>
property (section 4 in <span class="fig">A</span>).
The link is a path or URL to the target CATALOG file (<span class="fig">B</span>).</p>
<p>Each section can have optional <span class="prop">origin</span> and <span class="prop">direction</span> properties.
If omitted, <span class="prop">origin</span> has the default value of <span class="formula">000</span>
and <span class="prop">direction</span> has the default value of <span class="formula">100010001</span>
(i.e. the identity matrix).
An affine transformation is specified with these two keys and is applied to
the image (or images if the section is a link) in this section.</p>
<p>Images with integer values can contain the <span class="prop">annotation</span> property
(section 3 in <span class="fig">A</span>).
It is a path or URL to a plain text file containing annotations to different
values (<span class="fig">C</span>).
This example shows an annotation file converted from ABA's annotation
JSON file.
The columns from left to right are structure ID, parent structure ID, color,
structure abbreviation and name.</p>
</div>
</div>
<div class="section" id="browsing-data">
<h1><a class="toc-backref" href="#table-of-contents">Browsing Data</a></h1>
<div class="figure align-center" style="width: 80%">
<img alt="FNT user interface" id="fnt-ui" src="fnt-ui.png" style="width: 80%;" />
<p class="caption">FNT user interface.</p>
</div>
<p>Neurite tracing functionality is built upon interactive browsing of imaging
data.
The following sections explain how to browse imaging data in FNT.</p>
<div class="section" id="zooming">
<h2><a class="toc-backref" href="#table-of-contents">Zooming</a></h2>
<p>To zoom in, scroll the mouse wheel upwards when the mouse cursor is in
the 3D viewer.
To zoom out, scroll downwards.
Note that scrolling in 2D mode has no zooming effect.</p>
</div>
<div class="section" id="rotation">
<h2><a class="toc-backref" href="#table-of-contents">Rotation</a></h2>
<p>To rotate the view, push down left mouse button in the 3D viewer,
move the mouse to the direction of rotation,
and release left mouse button afterwards.</p>
</div>
<div class="section" id="visualization">
<h2><a class="toc-backref" href="#table-of-contents">Visualization</a></h2>
<p>The 3D viewer shows the maximum intensity projection of volumetric imaging
data by default.
Visualization in 2D mode is activated by holding the <span class="key">Shift</span> key.
A cross-section of the 3D volume is shown in this mode.
To show the subsequent neighboring cross-sections, scroll the mouse wheel.</p>
</div>
<div class="section" id="change-current-position">
<h2><a class="toc-backref" href="#table-of-contents">Change Current Position</a></h2>
<p>FNT handles big imaging data by only showing the data cubes around
the current position.
The current position is indicated by a circle at the center of the 3D viewer.
To browse data at another position, change the current position to
a new position.</p>
<p>If the X/Y/Z coordinates of the new position is known, they can be entered
in a dialog box to change the current position (<span class="ui">Position/Goto position</span>).
If the target position exists, it can be assigned to
the current position (<span class="ui">Position/Goto target</span>).
To jump to the soma of a neuron, select the neuron in the side panel
and execute <span class="ui">Neuron/Goto soma</span>.</p>
<p>If the current position is on an edge, moving the first slider in the side panel
will change the current position to neighboring positions on the edge.
The two buttons besides the slider are shortcuts for jumping to two vertices
of the edge.</p>
<p>The current position might be changed automatically after undoing/redoing
or after changing the state of a vertex.</p>
</div>
<div class="section" id="pick-target-position">
<h2><a class="toc-backref" href="#table-of-contents">Pick Target Position</a></h2>
<p>The target position is indicated by a cross.
It serves as an input for many tracing and editing operations.</p>
<p>The current position can also be assigned to the target
position (<span class="ui">Position/Pick current</span>).
If the target position is on an edge, moving the second slider in the side panel
will change the target position to neighboring positions on the edge.
The two buttons besides the slider are shortcuts for picking two vertices of
the edge.
To pick the soma of a neuron, select the neuron in the side panel and
execute <span class="ui">Neuron/Pick soma</span>.</p>
<div class="figure align-center" style="width: 80%">
<img alt="Examples of picking target position" id="pick-position" src="pick-position.png" style="width: 80%;" />
<p class="caption">Examples of picking target position.</p>
<div class="legend">
<span class="fig">A</span> shows how to pick a position in 3D mode.
<span class="fig">B</span> shows an example in 2D mode.</div>
</div>
<p>In 3D mode, left mouse clicking on an edge will pick the node of the edge
under mouse cursor.
If mouse cursor is not on an edge when clicking, a line segment appears.
Rotate the view and perform another mouse click near the line segment.
The two line segments determine a 3D position and that position is picked
as the target position.
An example is shown in <span class="fig">A</span>.
In 2D mode, a position on the currently shown cross-section is picked
with just one mouse click (<span class="fig">B</span>).</p>
<p>The target position might be changed automatically after undoing/redoing.</p>
</div>
<div class="section" id="data-loading">
<h2><a class="toc-backref" href="#table-of-contents">Data Loading</a></h2>
<p>By default, FNT automatically loads imaging data cubes near the
current position.
Automatic data loading can be disabled by unchecking <span class="ui">Position/Load data auto</span>.
After that, data can be manually loaded by executing <span class="ui">Position/Load data</span>.</p>
<p>Progress of data loading is shown in the status bar below the window.
Data loading can be cancelled by executing <span class="ui">Edit/Abort</span>.</p>
</div>
<div class="section" id="annotation">
<h2><a class="toc-backref" href="#table-of-contents">Annotation</a></h2>
<p>If there is an annotation channel (a channel with the <span class="prop">annotation</span>
property), it can be activated by selecting it in the annotation panel.
After that, the annotation data at the target position will be shown in the
annotation panel.</p>
</div>
</div>
<div class="section" id="tracing">
<h1><a class="toc-backref" href="#table-of-contents">Tracing</a></h1>
<p>The main tracing process consists of three steps: finding a putative path,
examining it and accepting it.
Accepted paths are used to create new edges or extend existing edges.
Edges can be modified or deleted.
It is possible to import neurites from SWC files or FNT files
(<span class="ui">Edit/Import SWC|FNT</span>).
All these operations can be undone (<span class="ui">Edit/Undo</span>).
Don't forget to save the tracing results before closing (<span class="ui">File/Save</span>).</p>
<div class="section" id="finding">
<h2><a class="toc-backref" href="#table-of-contents">Finding</a></h2>
<div class="figure align-center" style="width: 80%">
<img alt="Examples of finding putative paths" id="find-path" src="find-path.png" style="width: 80%;" />
<p class="caption">Examples of finding putative paths.</p>
<div class="legend">
<span class="fig">A</span> shows how to find a putative path starting from
the current position.
<span class="fig">B</span> shows how to find a putative path connecting
the current position and the target position.</div>
</div>
<p>Putative paths can be found in two approaches.
The first approach is to execute <span class="ui">Tracing/Find</span> and obtain a putative path
starting from the current position (<span class="fig">A</span>).
In more difficult cases, pick a target position on the neurite being traced
and execute <span class="ui">Tracing/Connect</span>.
A putative path connecting the current position and the target
position will be found (<span class="fig">B</span>).</p>
<p>Node properties of the found putative path can be changed by executing
<span class="ui">Tracing/Refine</span>.
For example, the Rayburst refine method can be used to estimate node radius.
In addition, a refine method can be chosen to run automatically for every
putative path.</p>
<p>The progress of finding, connecting or refining is shown in the status
bar below the window.
These actions can be cancelled when needed (<span class="ui">Edit/Abort</span>).</p>
</div>
<div class="section" id="examining">
<h2><a class="toc-backref" href="#table-of-contents">Examining</a></h2>
<p>The correctness of a putative path can be evaluated by comparing
it to real image signals of neurite structure.
For difficult cases, operations involving zooming, rotation and 2D
visualization can often help resolve complex neurite structure
under human perception.</p>
</div>
<div class="section" id="accepting">
<h2><a class="toc-backref" href="#table-of-contents">Accepting</a></h2>
<div class="figure align-center" style="width: 80%">
<img alt="Examples of accepting paths" id="add-path" src="add-path.png" style="width: 80%;" />
<p class="caption">Examples of accepting paths.</p>
<div class="legend">
Note the difference between <span class="ui">Extend</span> and <span class="ui">Branch</span>.</div>
</div>
<p>If the putative path is examined to be incorrect, just ignore it and
find another one.
If it is correct, add it to the tracing results by executing either
<span class="ui">Tracing/Branch</span> or <span class="ui">Tracing/Extend</span>.</p>
<p>Extending operation is slightly different from branching operation in that
the current position is changed to the new end point after the operation.
Extending operations are for tracing part of a linear structure
while branching operations are for adding initial segments of
branches at a branch point.</p>
</div>
<div class="section" id="traversal">
<h2><a class="toc-backref" href="#table-of-contents">Traversal</a></h2>
<p>A neuron has a tree structure.
A neuron tree can be completely traversed in a depth-first manner.
FNT allows depth-first traversal by recording the state of each vertex.
If all vertices of a traced neuron are in finished state, the neuron
is considered to be completely traced.
The following rules can ensure the completeness of tracing results.</p>
<p>When tracing of a branch comes to an end, change the state of the vertex at
the terminal by executing <span class="ui">Tracing/Done</span>.
This operation will set the state of the vertex to finished.
If there are unfinished vertices, the current position will be automatically
changed to the nearest unfinished vertex so that one can
immediately start tracing the unfinished branch.</p>
<p>At a branch point, trace the initial segment of each branch before continue
tracing one of the branches to the end.
The end points of all the initial segments are all marked in unfinished state
so that they will be automatically accessed at a latter time.
See the figure in the previous section for an example of tracing at branch
points.</p>
</div>
<div class="section" id="deletion">
<h2><a class="toc-backref" href="#table-of-contents">Deletion</a></h2>
<p>Edges can be deleted by executing <span class="ui">Tracing/Delete</span>.
If both the current position and the target position are on the same edge,
the part of the edge flanked by the two positions is deleted.
Otherwise if the target position is on an edge, the target edge is deleted.
If only the current position is on an edge, the current edge is deleted.</p>
</div>
<div class="section" id="modififcation">
<h2><a class="toc-backref" href="#table-of-contents">Modififcation</a></h2>
<p>Type of a node can be modified by executing <span class="ui">Edit/Change node type</span>,
<span class="ui">Tracing/Mark [1-3]</span> or <span class="ui">Tracing/Clear mark</span>.
Node radius can be modified by executing <span class="ui">Edit/Resize node</span>.
These operations modify the node at the target position.</p>
<p>Neurite type of an edge can be modified by executing
<span class="ui">Edit/Change neurite type</span>.
The modification is applied to the whole branch starting from soma
associated with the target position.</p>
</div>
<div class="section" id="neurons">
<h2><a class="toc-backref" href="#table-of-contents">Neurons</a></h2>
<p>To create a neuron, pick the soma position and execute <span class="ui">Neuron/New neuron</span>.
The list of all neurons are shown in the side panel.
Every neuron is assigned a name and can be renamed by executing
<span class="ui">Neuron/Rename neuron</span>.
A neuron can be deleted without removing its associated edges
(<span class="ui">Neuron/Remove neurons</span>) or purged by removing all associated edges
(<span class="ui">Neuron/Purge neurons</span>).</p>
</div>
<div class="section" id="shortcut-keys">
<h2><a class="toc-backref" href="#table-of-contents">Shortcut Keys</a></h2>
<p>Frequently used operations located in the <span class="ui">Tracing</span> menu
can be activated with just one key stroke to speed up tracing.</p>
<table border="1" class="docutils">
<colgroup>
<col width="34%" />
<col width="66%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Key</th>
<th class="head">Operation</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><span class="key">F</span></td>
<td>Find</td>
</tr>
<tr><td><span class="key">C</span></td>
<td>Connect</td>
</tr>
<tr><td><span class="key">R</span></td>
<td>Refine</td>
</tr>
<tr><td><span class="key">D</span></td>
<td>Done</td>
</tr>
<tr><td><span class="key">B</span></td>
<td>Branch</td>
</tr>
<tr><td><span class="key">Space</span></td>
<td>Extend</td>
</tr>
<tr><td><span class="key">1</span></td>
<td>Mark 1</td>
</tr>
<tr><td><span class="key">2</span></td>
<td>Mark 2</td>
</tr>
<tr><td><span class="key">3</span></td>
<td>Mark 3</td>
</tr>
<tr><td><span class="key">0</span></td>
<td>Clear mark</td>
</tr>
<tr><td><span class="key">X</span></td>
<td>Delete</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="miscellaneous">
<h2><a class="toc-backref" href="#table-of-contents">Miscellaneous</a></h2>
<p>There are additional useful functions under the <span class="ui">File/Misc</span> sub-menu, including</p>
<ul class="simple">
<li>saving the results of traced neurons to SWC files,</li>
<li>obtaining statistics of traced neurons,</li>
<li>annotating soma of traced neurons.</li>
</ul>
<p>The sub-menu can be further extended by including new plug-ins.</p>
</div>
</div>
<div class="section" id="configuration">
<h1><a class="toc-backref" href="#table-of-contents">Configuration</a></h1>
<p>There are several modifiable settings in FNT in the <span class="ui">Options</span> dialog box
(<span class="ui">File/Options</span>).</p>
<div class="section" id="cache">
<h2><a class="toc-backref" href="#table-of-contents">Cache</a></h2>
<p>Remote imaging data are cached in computer memory.
The amount of memory used for cacheing can be configured
under <span class="ui">Data/Cache/Memory usage</span>.
Parallel fetching of remote data is supporting by configuring
<span class="ui">Data/Cache/Cache parallelism</span>.
Pre-caching (<span class="ui">Data/Cache/Pre-cache parallelism</span>) can be used to
reduce waiting time while loading the data.
It can be disabled by setting the value to zero.</p>
</div>
<div class="section" id="loading">
<h2><a class="toc-backref" href="#table-of-contents">Loading</a></h2>
<p>The amount of data loaded is configured by <span class="ui">Data/Loading/Radius</span>.
If this value is too small, more frequent data loading is needed,
and the maximal length of putative paths is shortened.
On the other hand, bigger value requires more main memory and more video memory and increases time for data loading.</p>
</div>
<div class="section" id="channels">
<h2><a class="toc-backref" href="#table-of-contents">Channels</a></h2>
<div class="figure align-center" style="width: 80%">
<img alt="Examples of visualizing multiple channels" id="multi-ch" src="multi-ch.png" style="width: 80%;" />
<p class="caption">Examples of visualizing multiple channels.</p>
<div class="legend">
The left side shows the settings in the <span class="ui">Options</span> dialog box.
On the right side is the 3D visualization of the three selected channels.</div>
</div>
<p>FNT allows the visualization of at most 9 data channels at the same time.
Selected channels for visualization are divided to three
groups that can be configured in <span class="ui">Data/Channel</span>.
Channels in the same group are visualized in the same color.
Each channel is covered by preceding channels in the same group
and groups are blended together without covering.
Tracing operations use channel 1 in group 1.
The example shows how three channels including original data,
downsampled data and one of ABA's projection experiment,
are visualized simultaneously.</p>
<p>Transfer function for visualization can be modified for each channel.
Use the sliders or text entries to modify it.
To expand the range, enter an out-of-range value in the text entries.
To shrink the range, click <span class="ui">Shrink</span>.
Use <span class="ui">Reset</span> to restore the default range and reset the transfer function.
Note that changing transfer function might result in different
computation outcomes.</p>
</div>
<div class="section" id="display">
<h2><a class="toc-backref" href="#table-of-contents">Display</a></h2>
<p>Magnification factor of the 3D viewer can be modified with
<span class="ui">Display/General/Magnification</span>.
Values larger than 1 mean magnifying and can be used to reduce GPU usage
at the cost of reducing quality.
Values less than 1 mean minifying and can be used to produce high-quality
visualization.</p>
<p>Most colors used in FNT can be customized in <span class="ui">Display/Color</span>.
<span class="ui">Color[0-7X]</span> have different representations depending on the current color
mode.
Use the checkbox to change color mode.</p>
<p>Total number of slices for volume rendering with maximal intensity projection
can be modified (<span class="ui">Display/Volume/Total slices</span>).
Larger value results in better visualization quality.
The other setting is the number of slices actually shown (<span class="ui">Shown slices</span>).
Smaller value lowers GPU usage and can also be used to reduce the complexity
of visualized image.</p>
</div>
<div class="section" id="computation">
<h2><a class="toc-backref" href="#table-of-contents">Computation</a></h2>
<p>Progress information during computation can be displayed in the 3D viewer
at a given interval (<span class="ui">Compute/General/Update interval</span>).
The process of computation can be cancelled (<span class="ui">Edit/Abort</span>).</p>
<p>Different algorithms can be used for each type of computation.
Parameters for a specific algorithm can be modified.
The <span class="ui">Refine (auto)</span> computation is performed for each putative path
automatically.
To disable it, choose the dummy algorithm.</p>
<p>The set of algorithms can be further extended by including new plug-ins.</p>
</div>
</div>
<div class="section" id="tools">
<h1><a class="toc-backref" href="#table-of-contents">Tools</a></h1>
<p>FNT includes several programs of different utilities:</p>
<ul class="simple">
<li><code class="sh bash">fnt-slice2cube</code>, to convert TIFF slices to small 3D cubes;</li>
<li><code class="sh bash">fnt-dist</code>, to align neurons and compute the dissimilarities between
neurons based on the topology and geometry of their tracing results;</li>
<li><code class="sh bash">fnt-fromswc</code>, to convert SWC files to FNT files;</li>
<li><code class="sh bash">fnt-toswc</code>, to convert FNT files to SWC files;</li>
<li><code class="sh bash">fnt-join</code>, to join multiple FNT files into one output FNT file;</li>
<li><code class="sh bash">fnt-split</code>, to split one FNT file to multiple output FNT files;</li>
<li><code class="sh bash">fnt-lint</code>, to find putative tracing errors in FNT files.</li>
</ul>
<p>Run <code class="sh bash">COMMAND --help</code> to see the usage.</p>
</div>
<div class="section" id="id2">
<h1><a class="toc-backref" href="#table-of-contents">Miscellaneous</a></h1>
<div class="section" id="files-and-directories">
<h2><a class="toc-backref" href="#table-of-contents">Files and Directories</a></h2>
<p>Under Linux or Mac OS, FNT uses the <span class="fn">.fnt</span> directory under home directory
to store private data.
Under Windows, FNT uses the <span class="fn">fnt</span> directory under user directory for that
purpose.</p>
</div>
<div class="section" id="license">
<h2><a class="toc-backref" href="#table-of-contents">License</a></h2>
<p>FNT is licensed under <a class="reference external" href="http://gnu.org/licenses/gpl.html">GNU GPL version 3 or later</a>.</p>
</div>
<div class="section" id="author">
<h2><a class="toc-backref" href="#table-of-contents">Author</a></h2>
<ul class="simple">
<li>GOU Lingfeng &lt;<a class="reference external" href="mailto:goulf&#64;ion.ac.cn">goulf&#64;ion.ac.cn</a>&gt;</li>
</ul>
</div>
</div>
</div>
</body>
</html>
